feat(tags): adds `legacy_tag_formats` and `ignored_tag_formats` settings by noirbizarre · Pull Request #1297 · commitizen-tools/commitizen

noirbizarre · 2024-11-25T23:51:37Z

Description

This PR add 2 new settings to handle tag formats;

legacy_tag_formats allowing tag format to change over time while retaining the ability to work with legacy version
ignored_tag_formats to specify expected tag that should not raise InvalidVersion.

So projects which change tag formats and have expected but non-version tags can have these settings:

tag_format = "v${version}"
legacy_tag_formats = [
	"${version}",
	"project-prefix-${version}",
]
ignored_tag_formats = [
	"stable",
	"other-project-*",
]

By doing so, I had to start grouping tag handling and introduce a tags.TagRules object which is responsible for handling all tags rules, initially spread over tag_format, version_schemes and version_providers

Checklist

Add test cases to all the changes you introduce
Run ./scripts/format and ./scripts/test locally to ensure this change passes linter check and test
Test the changes on the local machine manually
Update the documentation for the changes

Expected behavior

I can change tag format and still being able to:
- bump versions (aka. find the increment and commits range)
- generate changelog (full, incremental, version range)
I can generate a changelog without warnings for expected tags

Steps to Test This Pull Request

create a project
set version_provider = "scm" (not mandatory but allows testing the full scope)
bump some versions with an initial tag_format
move current tag_format in legacy_tag_format and define a new tag_format
bump a version with changelog:
- current version should be properly identified
- increment should properly been found
- new version should be correct
- generated changelog generation should be correct (both new and old version formats)
- new tag should respect the new tag_format

then:

add random-* to ignored_tag_formats
tag any commit with random-tag
run cz changelog
- there shouldn't be any warning

Additional context

There might be a 2nd PR handling a changelog_version_format setting to customize the version rendering in the changelog so:

it's not the tag format anymore (problematic with some prefixes, like for monorepos)
have a uniform version display across tag_format changes

codecov · 2024-11-25T23:54:16Z

Codecov Report

Attention: Patch coverage is 99.45055% with 1 line in your changes missing coverage. Please review.

Project coverage is 97.67%. Comparing base (120d514) to head (37c45cd).
Report is 569 commits behind head on master.

Files with missing lines	Patch %	Lines
commitizen/commands/bump.py	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1297      +/-   ##
==========================================
+ Coverage   97.33%   97.67%   +0.33%     
==========================================
  Files          42       56      +14     
  Lines        2104     2625     +521     
==========================================
+ Hits         2048     2564     +516     
- Misses         56       61       +5

Flag	Coverage Δ
unittests	`97.67% <99.45%> (+0.33%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Lee-W · 2024-12-06T15:13:47Z

wow, this is a huge one. I'll be mostly out for the following month but will try to take a look after I'm back

noirbizarre · 2024-12-06T18:39:42Z

Yes, I know, sorry. I had this idea long ago, just not had time to cover it all until now.
Actually, this is as of today the main remaining pain point I have. I had to migrate a lot of projects on different tagging conventions in a corporate environment and as of today it involves lots of manual steps as well as features lost.
So 🎉 there it is, this one fixes all my cases (and I'm sure I'm not the only one facing those).

In the meantime, enjoy your holidays !

woile · 2024-12-07T08:33:02Z

Could you add a tutorial for this case? Otherwise it feels like we are adding a lot of features and it's unclear what a user can do with them.
I'll review it this week 👍🏻

noirbizarre · 2024-12-07T21:00:26Z

I completed the monorepo tutorial and added a FAQ entry but yes, I can totally write a full tutorial on changing tag convention while keeping backward compatibility 👍🏽

Lee-W

Hey @noirbizarre , thanks for making such an awesome PR! I left a few questions. I think we might need a few rounds of change and discussions before merging. But again, this is great!

docs/faq.md

commitizen/defaults.py

commitizen/version_schemes.py

commitizen/tags.py

commitizen/changelog_formats/markdown.py

commitizen/providers/scm_provider.py

commitizen/tags.py

woile · 2025-02-08T10:55:17Z

I like this a lot 💪🏻 super cool work! if possible please add some tests for test_tag mainly to understand how its api should be used. I think most of the coverage probably comes from the other tests, but still it would be nice, at a quick glance on a test to see how it works.

docs/tutorials/tag_format.md

noirbizarre · 2025-02-08T11:54:01Z

I'll add some examples. I already pushed a few changes/fixes.
It started with a use case I have on lot of projects at work (tag convention that changed) and while working on this, I realized the tag management logic spread on multiple modules, that many things depends on it but on different phases, used in and that it was difficult to change, so I introduced the TagRules object. It should make easier to work on this kind of topic later.

Anyway, I have some time today, I'll advance the documentation and rework and hope to be able to provide a new iteration

noirbizarre · 2025-02-08T22:10:46Z

There it is, PR updated with:

a tutorial
more docstrings and examples
all comments applied

I noticed a few possible edge-cases (not introduced in this PR) I might handle after this PR.

Example: it is possible to have tag_format = ${major} and then, tree processing is broken, incremental changelog is broken, version ranging is broken...
It is logical, but I think it is worth documenting it, and I think that's why there were 2 different logics (that I kept as it is in this PR to avoid regressions) for version parsing:

1 assuming that it's possible to have only ${major} or ${major}.${minor} as tag format
1 assuming version sorting, changelog rendering always requires the full version

One solution may be to only allow ${version} in tag format and support some extra tag format (which would in addition allow bumping v3.2.1, v3.2 ad v3 at the same time, which have some use cases like GitHub actions versioning). But that's another story

noirbizarre · 2025-02-26T00:18:02Z

@woile @Lee-W, if this is ok for you, I would love to merge this one too as I have addressed all comments.
(Given this is not a small Pr, keeping it open leads to conflicts and rebases)

Lee-W · 2025-02-26T02:46:23Z

@woile @Lee-W, if this is ok for you, I would love to merge this one too as I have addressed all comments. (Given this is not a small Pr, keeping it open leads to conflicts and rebases)

I'll try to take a look tomorrow or Friday, but feel free to merge it without me 🙂

noirbizarre · 2025-02-26T11:13:59Z

I'll wait for your feedback 👍🏼

commitizen/changelog_formats/base.py

Lee-W · 2025-03-02T02:31:01Z

My comment is non-blocking. Feel free to merge it or make changes if you deem necessary. Awesome PR. Thanks a lot!

noirbizarre · 2025-03-02T15:27:32Z

Thanks ! 🙏🏼
PR merged, I'll be reactive if any breakage is introduced (but it shouldn't given how it has been tested)

carlossg · 2025-03-21T16:39:30Z

this PR causes cz bump to break when one tag is invalid, see #1375

Starting in 4.4.0 due to commitizen-tools#1297 when an invalid tag is present an exception is thrown This commit ignores the invalid tags Follow up from commitizen-tools#1375

noirbizarre requested review from Lee-W and woile as code owners November 25, 2024 23:51

github-actions bot added the pr-status: wait-for-review label Nov 25, 2024

noirbizarre added the type: feature A new enhacement proposal label Nov 26, 2024

noirbizarre force-pushed the feat/known-tag-formats branch 4 times, most recently from dc08a79 to c1f2e4f Compare November 28, 2024 00:52

Lee-W reviewed Jan 30, 2025

View reviewed changes

Lee-W added pr-status: wait-for-modification and removed pr-status: wait-for-review labels Jan 30, 2025

github-actions bot added the pr-status: wait-for-review label Feb 7, 2025

noirbizarre force-pushed the feat/known-tag-formats branch from 844c5e2 to fa48ec9 Compare February 8, 2025 01:53

Lee-W removed the pr-status: wait-for-review label Feb 8, 2025

woile reviewed Feb 8, 2025

View reviewed changes

commitizen/tags.py Show resolved Hide resolved

woile reviewed Feb 8, 2025

View reviewed changes

docs/tutorials/tag_format.md Show resolved Hide resolved

noirbizarre force-pushed the feat/known-tag-formats branch from fa48ec9 to 7f7f8bd Compare February 8, 2025 19:15

github-actions bot added the pr-status: wait-for-review label Feb 8, 2025

noirbizarre force-pushed the feat/known-tag-formats branch 5 times, most recently from c9d956e to 070bfdf Compare February 8, 2025 21:54

noirbizarre added 2 commits February 8, 2025 22:55

refactor(get_tag_regexes): dedup tag regexes definition

565f9a3

feat(tags): adds legacy_tag_formats and ignored_tag_formats settings

37c45cd

noirbizarre force-pushed the feat/known-tag-formats branch from 070bfdf to 37c45cd Compare February 8, 2025 21:56

Lee-W approved these changes Feb 28, 2025

View reviewed changes

commitizen/changelog_formats/base.py Show resolved Hide resolved

noirbizarre merged commit 74554c2 into commitizen-tools:master Mar 2, 2025
18 checks passed

noirbizarre deleted the feat/known-tag-formats branch March 2, 2025 15:26

noirbizarre mentioned this pull request Mar 2, 2025

feat: Introduce tag_regex option with smart default #692

Closed

4 tasks

carlossg mentioned this pull request Mar 21, 2025

fix: display invalid tag information #1375

Merged

4 tasks

carlossg mentioned this pull request May 12, 2025

fix: ignore invalid tags #1410

Closed

4 tasks

noirbizarre mentioned this pull request May 15, 2025

fix(bump): don't fail if an invalid version tag is present (fix #1410) #1418

Merged

10 tasks

Uh oh!

Conversation

noirbizarre commented Nov 25, 2024

Description

Checklist

Expected behavior

Steps to Test This Pull Request

Additional context

Uh oh!

codecov bot commented Nov 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Lee-W commented Dec 6, 2024

Uh oh!

noirbizarre commented Dec 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

woile commented Dec 7, 2024

Uh oh!

noirbizarre commented Dec 7, 2024

Uh oh!

Lee-W left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

woile commented Feb 8, 2025

Uh oh!

Uh oh!

noirbizarre commented Feb 8, 2025

Uh oh!

noirbizarre commented Feb 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

noirbizarre commented Feb 26, 2025

Uh oh!

Lee-W commented Feb 26, 2025

Uh oh!

noirbizarre commented Feb 26, 2025

Uh oh!

Uh oh!

Lee-W commented Mar 2, 2025

Uh oh!

Uh oh!

noirbizarre commented Mar 2, 2025

Uh oh!

carlossg commented Mar 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov bot commented Nov 25, 2024 •

edited

Loading

noirbizarre commented Dec 6, 2024 •

edited

Loading

noirbizarre commented Feb 8, 2025 •

edited

Loading